Update instructions/wordpress.instructions.md - #2848
Open
soderlind wants to merge 10 commits into
Open
Conversation
- Introduced a detailed guide covering core principles, coding standards, security practices, internationalization, performance optimization, admin UI, REST API, block development, asset loading, testing strategies, and documentation best practices. - Emphasized the importance of following WordPress Coding Standards (WPCS) and provided examples for plugin headers, linting setup, and security measures. - Included a checklist to ensure compliance with best practices for plugin development.
… security, and testing rules for plugins and themes
…ging double quotes to single quotes for 'applyTo' and 'description' fields.
Cover prefixing, safe paths, filesystem writes, distribution archive hygiene, updater policy, settings sanitization, translations, metadata, escaping, trademarks, external services, and public URL checks, plus a WordPress.org self-audit command block. Assisted-by: GitHub Copilot:Claude Opus 4.8
Contributor
There was a problem hiding this comment.
Pull request overview
Adds WordPress development and directory-review guidance to the instruction catalog.
Changes:
- Adds WordPress coding, security, testing, and release guidance.
- Adds WordPress.org self-audit commands.
- Registers the instruction in the generated index.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
README.instructions.md |
Adds the WordPress instruction catalog entry. |
instructions/wordpress.instructions.md |
Defines WordPress development and directory-review guidance. |
Suppressed comments (2)
instructions/wordpress.instructions.md:73
- This
//annotation makes the package manifest invalid JSON if the suggested snippet is copied. Move the label outside the code block or remove it.
// package.json (snippet)
{
instructions/wordpress.instructions.md:150
- As above, the comment before this XML declaration makes the copied
phpunit.xml.distinvalid. Put the declaration first so PHPUnit can parse the sample configuration.
<!-- phpunit.xml.dist (minimal) -->
<?xml version="1.0" encoding="UTF-8"?>
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+57
to
+58
| // composer.json (snippet) | ||
| { |
Comment on lines
+200
to
+206
| grep -rnE "function |^\s*(class|trait|interface) |namespace |define\(|const " src/ includes/ *.php | ||
| grep -rnE "update_option\(|get_option\(|add_option\(|set_transient\(|get_transient\(" src/ includes/ *.php | ||
| grep -rnE "WP_PLUGIN_DIR|WP_CONTENT_DIR|WP_CONTENT_URL|WPMU_PLUGIN_DIR|ABSPATH|__DIR__" src/ includes/ *.php | ||
| grep -rnE "file_put_contents|fopen|fwrite|fputs|mkdir|unlink|rename\(|copy\(" src/ includes/ *.php | ||
| grep -rniE "plugin-?update-?checker|PucFactory|pre_set_site_transient_update_plugins|puc_" . | ||
| grep -rnE "wp_remote_|curl_|file_get_contents\('https?://|https?://" src/ includes/ *.php | ||
| grep -rnE "<script|<style" src/ includes/ templates/ *.php |
Comment on lines
+212
to
+213
| wp dist-archive . | ||
| unzip -l my-plugin.zip |
| @@ -0,0 +1,232 @@ | |||
| --- | |||
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (5)
Previously missed (3) — in code that hasn't changed since the last review.
instructions/wordpress.instructions.md:73
- This line makes the advertised
package.jsonsnippet invalid JSON, so copying it causes npm to reject the manifest. Remove the JavaScript-style comment or move the label outside the JSON fence.
// package.json (snippet)
instructions/wordpress.instructions.md:139
- There is no
wp_register_style/scriptAPI; WordPress exposes two separate functions. Naming both explicitly avoids directing Copilot to generate an undefined function call.
- Use `wp_register_style/script` to register first if multiple components depend on the same assets.
instructions/wordpress.instructions.md:205
- This audit misses WordPress's
wp_safe_remote_*()APIs becausewp_remote_is not a substring of those names. A service call such aswp_safe_remote_get( $endpoint )can therefore escape both this check and the literal-URL check when the endpoint is dynamic.
grep -rnE "wp_remote_|curl_|file_get_contents\('https?://|https?://" src/ includes/ *.php
instructions/wordpress.instructions.md:57
- This line makes the advertised
composer.jsonsnippet invalid JSON, so copying it causes Composer to reject the manifest. Remove the JavaScript-style comment or move the label outside the JSON fence.
// composer.json (snippet)
instructions/wordpress.instructions.md:213
wp dist-archive .does not guarantee a file namedmy-plugin.zip; when a version is discoverable, its default filename includes that version, so the next command can fail. Pass the intended target explicitly before inspecting it.
wp dist-archive .
unzip -l my-plugin.zip
bishop335
reviewed
Aug 28, 2026
…rministic dist-archive - Move composer.json/package.json labels outside JSON fences so snippets are valid JSON - Scan self-audit greps from project root with --include='*.php' and vendor/node_modules excludes - Pass explicit target to wp dist-archive for a deterministic archive name Assisted-by: GitHub Copilot:Claude Opus 4.8
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Suppressed comments (5)
Previously missed (1) — in code that hasn't changed since the last review.
instructions/wordpress.instructions.md:20
- This PHP example also contradicts the instruction to follow WPCS by omitting the required spacing inside the function call. Copilot may reproduce the example verbatim, so the scaffold should model the stated standard.
This issue also appears in the following locations of the same file:
- line 124
- line 165
defined('ABSPATH') || exit;
instructions/wordpress.instructions.md:1
- The diff adds this as a new 234-line file and adds a new README catalog entry, but the PR description says this is an update to an existing file whose README entry is unchanged. Please reconcile the PR description and checklist with the actual new-resource change so reviewers can assess the correct scope.
---
instructions/wordpress.instructions.md:211
- The archive audit misses the
phpunit.xml.distfile recommended earlier in this same instruction (lines 150-159), because*.phpunit*does not match filenames beginning withphpunit. Include PHPUnit configuration filenames so the production-archive check catches this development tooling.
find . -type f \( -name '*.po' -o -name '*.mo' -o -name '*.l10n.php' -o -name '*.phpunit*' -o -name '*.result.cache' \)
instructions/wordpress.instructions.md:127
- This sample is presented immediately after requiring WPCS, but its function calls and indentation do not follow WordPress PHP formatting, so generated code copied from it will fail the recommended PHPCS checks.
add_action('wp_enqueue_scripts', function () {
wp_enqueue_style(
'af-frontend',
plugins_url('assets/frontend.css', __FILE__),
instructions/wordpress.instructions.md:168
- The testing example uses non-WPCS function-call spacing and space indentation even though this instruction directs generated PHP to pass WPCS. Format the example consistently so copying it does not introduce PHPCS violations.
$_tests_dir = getenv('WP_TESTS_DIR') ?: '/tmp/wordpress-tests-lib';
require_once $_tests_dir . '/includes/functions.php';
tests_add_filter( 'muplugins_loaded', function () {
require dirname(__DIR__) . '/awesome-feature.php';
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
Suppressed comments (4)
Previously missed (3) — in code that hasn't changed since the last review.
instructions/wordpress.instructions.md:139
- This example contradicts the instruction to follow WPCS: it omits spaces inside function-call parentheses, uses short array syntax, and uses space indentation. The recommended PHPCS configuration will flag code copied from this block, so make the example WPCS-compliant.
This issue also appears on line 165 of the same file.
add_action('wp_enqueue_scripts', function () {
wp_enqueue_style(
'af-frontend',
plugins_url('assets/frontend.css', __FILE__),
[],
README.instructions.md:96
- This new catalog entry and the all-added instruction diff contradict the PR description's claim that an existing file is merely updated and that
README.instructions.mdneeds no regeneration. Clarify whether this is intentionally a new instruction and update the title, checklist, description, and additional notes accordingly; otherwise the branch appears to be based on the wrong baseline.
| [WordPress Development — Copilot Instructions](instructions/wordpress.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md) | Coding, security, and testing rules for WordPress plugins and themes |
instructions/wordpress.instructions.md:20
- The minimal scaffold itself does not follow the WPCS spacing required by this instruction and the supplied PHPCS ruleset. Use the standard spacing so Copilot is not taught a pattern that its own lint command rejects.
defined('ABSPATH') || exit;
instructions/wordpress.instructions.md:168
- This second PHP example also conflicts with the WPCS requirement:
getenv()anddirname()lack inner spacing, and the closure body uses spaces rather than tabs. Make all provided PHP examples pass the recommended PHPCS configuration.
$_tests_dir = getenv('WP_TESTS_DIR') ?: '/tmp/wordpress-tests-lib';
require_once $_tests_dir . '/includes/functions.php';
tests_add_filter( 'muplugins_loaded', function () {
require dirname(__DIR__) . '/awesome-feature.php';
| @@ -0,0 +1,234 @@ | |||
| --- | |||
| applyTo: 'wp-content/plugins/**,wp-content/themes/**,**/*.php,**/*.inc,**/*.js,**/*.jsx,**/*.ts,**/*.tsx,**/*.css,**/*.scss,**/*.json' | |||
|
|
||
| ```bash | ||
| grep -rnE --include='*.php' --exclude-dir=vendor --exclude-dir=node_modules "function |^[[:space:]]*(class|trait|interface) |namespace |define\(|const " . | ||
| grep -rnE --include='*.php' --exclude-dir=vendor --exclude-dir=node_modules "update_option\(|get_option\(|add_option\(|set_transient\(|get_transient\(" . |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Suppressed comments (6)
Previously missed (3) — in code that hasn't changed since the last review.
instructions/wordpress.instructions.md:1
- The PR description says this is an update to an existing instruction and that only the Directory Review section changed, but this diff creates the entire file (
-0,0) and adds its first README entry. Please update the PR description/type so reviewers can accurately assess the full new instruction.
---
instructions/wordpress.instructions.md:141
wp_register_style/scriptis not a WordPress API and can be copied as a nonexistent function name. Name the two actual APIs explicitly.
This issue also appears on line 212 of the same file.
- Use `wp_register_style/script` to register first if multiple components depend on the same assets.
instructions/wordpress.instructions.md:20
- This guard omits the function-call spacing required by the instruction's own WPCS rule, so the canonical plugin scaffold will fail the recommended PHPCS check.
This issue also appears in the following locations of the same file:
- line 124
- line 165
defined('ABSPATH') || exit;
instructions/wordpress.instructions.md:212
- The setup names the ruleset
phpcs.xmlon line 42, but this command explicitly requiresphpcs.xml.dist; following the snippets verbatim therefore fails with a missing ruleset. Let PHPCS discover the standard ruleset it just instructed users to create.
./vendor/bin/phpcs --standard=phpcs.xml.dist .
instructions/wordpress.instructions.md:128
- This canonical asset example violates both requirements it introduces: its function-call formatting is not WPCS-compliant, and the two-character
afhandle prefix is shorter than the required four characters on line 184. Code generated from the example will fail the recommended checks.
add_action('wp_enqueue_scripts', function () {
wp_enqueue_style(
'af-frontend',
plugins_url('assets/frontend.css', __FILE__),
[],
instructions/wordpress.instructions.md:169
- This bootstrap example also conflicts with the instruction's WPCS/prefix rules: calls omit required spacing, indentation uses spaces, and the file-scope variable has only the disallowed two-character
afprefix. The supplied test scaffold will therefore fail the checks users are told to run.
$_tests_dir = getenv('WP_TESTS_DIR') ?: '/tmp/wordpress-tests-lib';
require_once $_tests_dir . '/includes/functions.php';
tests_add_filter( 'muplugins_loaded', function () {
require dirname(__DIR__) . '/awesome-feature.php';
} );
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Suppressed comments (2)
Previously missed (2) — in code that hasn't changed since the last review.
instructions/wordpress.instructions.md:196
Plugin URIandAuthor URIare fields of the main plugin PHP header, notreadme.txtfields. The official Plugin Handbook documents them as plugin-header metadata, so this wording directs the audit to the wrong file.
- Verify that `Plugin URI`, `Author URI`, and repository, documentation, terms, and privacy URLs in `readme.txt` are public and resolve successfully. Remove stale or private links.
README.instructions.md:96
- This newly added catalog entry and the all-added instruction diff conflict with the PR description's claims that this is an update to an existing file and that
README.instructions.mdneeds no regeneration. Please update the title, contribution type, and Additional Notes so reviewers and release tooling treat this as a new instruction.
| [WordPress Development — Copilot Instructions](instructions/wordpress.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md) | Coding, security, and testing rules for WordPress plugins and themes |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (5)
Previously missed (3) — in code that hasn't changed since the last review.
instructions/wordpress.instructions.md:152
- An XML declaration must precede all other document content. Copying this minimal
phpunit.xml.distverbatim leaves a comment before the declaration and makes the XML invalid; move the file label after the declaration.
This issue also appears on line 163 of the same file.
<!-- phpunit.xml.dist (minimal) -->
<?xml version="1.0" encoding="UTF-8"?>
instructions/wordpress.instructions.md:20
- This guard does not follow the WPCS function-call spacing that the instructions require, so the provided PHPCS rules will flag code copied from the example.
This issue also appears on line 124 of the same file.
defined('ABSPATH') || exit;
README.instructions.md:96
- The PR description says this updates an existing instruction and requires no README regeneration, but this new catalog row and the full-file addition show that a new instruction is being introduced. Update the description and contribution checklist so reviewers apply the new-resource requirements.
| [WordPress Development — Copilot Instructions](instructions/wordpress.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fwordpress.instructions.md) | Coding, security, and testing rules for WordPress plugins and themes |
instructions/wordpress.instructions.md:164
- This file sketch places text before the PHP opening tag, so loading the bootstrap emits the
// tests/bootstrap.phpline as output instead of treating it as a comment. Put<?phpfirst; the replacement also makes the sample consistent with the WPCS spacing required above.
// tests/bootstrap.php (minimal sketch)
<?php
instructions/wordpress.instructions.md:128
- This generated-code example conflicts with the WPCS requirement above: its function calls omit required argument spacing, use space indentation, and use short array syntax. The supplied
WordPressPHPCS standard will flag the example, so present the snippet in the same style users are instructed to enforce.
add_action('wp_enqueue_scripts', function () {
wp_enqueue_style(
'af-frontend',
plugins_url('assets/frontend.css', __FILE__),
[],
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request Checklist
npm startand verified thatREADME.mdis up to date.mainbranch for this pull request.Description
Updates
instructions/wordpress.instructions.mdwith guidance distilled from real WordPress.org Plugin Directory review feedback — the checks a human reviewer (or their AI pre-scan) raises that local Plugin Check/PHPCS often miss.Adds a new "WordPress.org Directory Review" section plus a self-audit command block covering:
wp_/generic prefixes).__FILE__(no internal location constants).WP_Filesystemusage..distignore,wp dist-archive, excluding dev/test/compiled-translation files).register_setting()sanitization callbacks.readme.txtmetadata,Contributors:slug ownership, escaping, trademark/naming rules, external-service disclosure, and valid public URLs.Also refines the i18n guidance to reflect automatic translation loading since WordPress 4.6.
Type of Contribution
Additional Notes
descriptionis unchanged, soREADME.mdrequires no regeneration.markdownlint(clean) andgit diff --check(clean). Pre-existing lint findings elsewhere in the file are unrelated and left untouched.By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.